Skip to content

trains: prescribed-signal inverse EPG and Busse train design in a C++ kernel - #56

Merged
mcencini merged 5 commits into
mainfrom
busse-inverse-epg
Nov 11, 2026
Merged

mcencini merged 5 commits into
mainfrom
busse-inverse-epg

Conversation

@mcencini

@mcencini mcencini commented Nov 10, 2026 •

Copy link
Copy Markdown
Contributor

What

blochsim.trains is new: refocusing trains designed from the echo signal they are to give. It replaces the NumPy EPG that pypulseqpp grew for this (pypulseqpp _busse.py, _pd.py, _fse_contrast.py), so the phase graph lives in one package.

Function Does
prescribed_flips Inverts the phase graph of a CPMG train echo by echo: the smallest flip angle in [0, 180] whose echo has the prescribed amplitude, with or without relaxation. Batched, variable lengths.
busse_flips Busse (2006, 2008) variable-flip-angle trains from a lowest, a centre and a highest angle. Batched over lengths, angles and centre echoes.
busse_centre_echo The centre echo whose contrast-equivalent TE is nearest a target: every candidate centre is designed in one batch (pypulseqpp bisected over candidates in Python).
effective_te Contrast-equivalent echo time of every echo of a train.

Design

  • Kernel. _trains_cpu.cpp is a third CPU extension: double precision, host only, torch-free, threaded over the trains of a batch on the existing WorkerPool. It has two entry points, inverse and forward.
  • Shared operators. The real-subspace shift and rotation are now templates over the number type in _real_subspace.hpp. _epg_cpu.cpp uses them at float (shift_real, simulate_real_range), the new kernel at double. The CPMG train is the second real subspace (transverse along the pulse axis), which differs from the engine's only in the sign of the shift's conjugate coupling.
  • No GPU counterpart. A schedule is solved once, in microseconds per train, and its shooting residual needs double precision. This is a deliberate exception to "every path exists on both sides".
  • Busse solver. The inversion is causal, so the three controls decouple: the first two are solved against the lowest angle before the centre and the angle at it (damped Newton, differenced Jacobian, on trains cut at the centre); the third is then bracketed against the last angle alone (Illinois). An echo out of reach adds its shortfall to the residual, so the solver keeps a gradient where clipped angles have none. MINPACK's hybrid method (SciPy, imported lazily) is the fallback for a stalled first stage.
  • import blochsim is lazy (second commit; no lock of its own, so the import system sees every cycle between threads, and a private name that is not a submodule is an AttributeError without loading anything). It imports blochsim.trains alone; everything built on PyTorch loads on first use (attribute, from blochsim import ..., submodule, dir, __all__). Without this, a consumer designing a train would pay for import torch (1.6-2.2 s measured here, import blochsim 2.5-3.5 s) to run a 30 ms solve. The commit is separable: reverting it leaves blochsim.trains working, at torch's import cost.
  • Fork-safe pool (second commit). WorkerPool is tied to the process that created it. A child forked after a threaded kernel call used to wait forever on workers it does not have; it now starts its own pool.

Measured

Laptop (20 threads, load average about 30 during the runs, so absolute numbers are pessimistic).

NumPy (pypulseqpp 0.0.62) this PR
Centre search + schedule, ETL 60 + 6 startup, fresh process 460-550 ms 32-36 ms
Same, warm 340-375 ms 28 ms
One Busse schedule, CPU time, mean over 1500 random prescriptions 92 ms 4.5 ms
Inverse of one 60-echo train (kernel, CPU time) not re-measured on a quiet machine 13-17 µs
PD schedule (make_pd_schedule, 26-166 pulses), through pypulseqpp 0.5-3.2 s 10-53 ms
import blochsim.trains after NumPy n/a 1.6 ms, torch not imported

Agreement with the NumPy implementation:

  • Kernel inverse: angles within 2.5e-11 deg, echoes within 7e-14, on Busse, random (mostly unreachable) and relaxed targets. Effective TE within 1.3e-12 s.
  • 1500 random Busse prescriptions (length 16-199, any centre, max flip up to 179): all 1063 the NumPy solver could design are designed, largest angle difference 1.2e-8 deg; 91 more are designed that MINPACK alone failed on (they meet the same acceptance tests). 60 needed the MINPACK fallback.
  • Float real-subspace kernel after the refactor: identical checksums, CPU time within noise of main (FSE, 20 000 voxels, 128 echoes, 10 and 32 states).

Tests

  • tests/trains/ (94 tests): echoes checked by isochromat summation written in tests/utils/isochromats.py; closed forms (180 degree train, first echo); the pseudo-steady-state amplitude against SciPy's Legendre function; the 106-pulse Busse Figure 1 train against a frozen reconstruction; centre search against a one-at-a-time loop; batch equals alone, bit for bit; torch-free import and lazy-load routes in subprocesses; pool after fork.
  • Full suite, pytest tests -n 6, CPU build with host kernels: 1644 passed, 327 skipped, 5 failed. Four were the new docstrings not following test_docstring_defaults (fixed, now pass). One, test_an_image_quality_design_fits_in_its_budget, is a 3 s wall-clock budget that failed under load and passes alone.
  • ruff check and ruff format --check clean on src, tests, scripts.

Not verified here: the MSVC, clang (macOS) and musl builds of the new extension (this PR's Wheels run is the first); a docs build; the CUDA wheels (unchanged sources, but they rebuild).

After review

  • The lazy import held its own lock and deadlocked when one thread used blochsim.Simulator while another imported blochsim.estimators on an install without _gpu. The lock is removed; three two-thread tests with a timeout cover it, and the reviewer's probe passes 3 of 3.
  • prescribed_flips raises on non-finite amplitudes or first angles; in the kernel a NaN echo now leaves NaN angles after it instead of zeros.
  • busse_flips broadcasts centre_echo and startup_echoes into the batch shape.
  • Tests added for the MINPACK fallback (found, and not found), the no-centre error, and the above. tests/trains is now 104 tests.
  • CHANGELOG entries appear once.

Release

pypulseqpp's follow-up PR needs this on PyPI as 0.0.18. Tag v0.0.18 on main after merge (Tag workflow from the Actions page, or git tag v0.0.18 && git push origin v0.0.18). wheels.yml then builds the sdist, the CPU wheels and blochsim-cuda12 / blochsim-cuda13, and publishes all three projects to PyPI through trusted publishing (environments pypi, pypi-cuda12, pypi-cuda13). The CUDA builds are PyPI projects, not GitHub release assets. scripts/check_wheel.py now expects three CPU kernels.

🤖 Generated with Claude Code

mcencini and others added 4 commits November 10, 2026 21:04
… kernel

blochsim.trains designs refocusing trains from the echo signal they are to
give: prescribed_flips inverts the phase graph of a CPMG train echo by echo,
busse_flips builds the Busse variable-flip-angle trains on it, effective_te
gives the contrast-equivalent echo time, and busse_centre_echo places the
centre echo for one by trying every centre in a batch.

The kernel (_trains_cpu) is double precision, host only, threaded over the
trains of a batch, and takes NumPy arrays. It shares the real-subspace shift
and rotation with the float simulation kernel through _real_subspace.hpp.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
import blochsim imports blochsim.trains alone, so a train is designed at
NumPy's import cost; everything built on PyTorch is imported the first time
it is asked for. The CPU kernels' worker pool is tied to the process that
created it, so a child forked after a threaded call does not wait on workers
it does not have.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The lazy import held a lock of its own while importing subpackages, and a
missing optional module asked for by 'from blochsim import _gpu' took it
too: one thread using blochsim.Simulator and another importing
blochsim.estimators waited on each other. The lock is gone, so the import
system sees every cycle, and a private name that is no submodule is an
AttributeError without loading anything.

prescribed_flips refuses amplitudes and first angles that are not finite,
and in the kernel an echo that is not a number leaves every later angle
not a number, where it left zeros. busse_flips broadcasts centre_echo and
startup_echoes into the batch shape. The MINPACK fallback and the
no-centre error are tested. The changelog entries are once.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@mcencini
mcencini marked this pull request as ready for review November 11, 2026 01:30
@mcencini
mcencini merged commit ad0822f into main Nov 11, 2026
35 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant